This adds a helper function that can import Storybook stories from fenced code blocks in markdown files. It's surprisingly easy, thanks to remark and unist plugins!

JS

In a module's stories.js or stories/*.js file:

import React from 'react'
import { storiesOf } from '@storybook/react'
import storiesFromMarkdown from '../../.storybook/lib/storiesFromMarkdown'

const stories = storiesOf('My module name', module)

// this will grab all of the .md files; you can tighten the pattern for each module
storiesFromMarkdown(require.context('.', true, /\.md$/))
  .forEach(({title, story}) => {
    stories.add(title, story)
  })

Note: require.context() is a webpack thing that facilitates dynamic require() statements. I've added the raw-loader per these instructions, which is how webpack is able to read the markdown files as strings when you do something like require('README.md').

Markdown

In your README.md or docs/*.md, write fenced code blocks with the html lang and optional metadata in key-value pairs. The following rules apply:

• Code blocks with story=false (or story="false") will be ignored.

• The title metadata can be used to provide an explicit title for each code block:

  ```html title="this is my story title"
  story here
  ```

• Otherwise, the text of the preceding heading will be used as the title, as in:

  # This is my story title
  
  Anything other than headings is ignored.
  
  ```html
  story here
  ```

• Because titles can't be repeated, multiple code blocks preceded by a single heading will get placeholder titles in the form story @ {file}:{line}.

And that's it! For a working example, see primer-breadcrumb/stories.js and the accompanying README.md.

/cc @primer/ds-core